{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 3 - Create a New Parcel Record\n",
    "\n",
    "\n",
    "The parcel fabric is a record-driven system. The parcel fabric organizes parcel data based on the form in which it was originally recorded. Parcel data is recorded on legal records such as plans, plats, deeds, and records of survey. Parcels are created and edited in response to changes in the legal record, and parcels are edited using record-driven workflows.\n",
    "\n",
    "The parcel fabric preserves historic and parent parcels. By capturing the legal record that created or retired a parcel, the parcel lineage can be tracked in both directions. In an enterprise deployment, all edits are tracked, and the parcel fabric can be compared with its state in a previous moment in time.\n",
    "\n",
    "Creating a parcel record requires the VersionManagementServer for branch versioning. However, it does not require access to the ParcelManager.  Creating a new record makes use of the ApplyEdits method of the REST API which is accessed through the FeatureServer endpoint.\n",
    "\n",
    "In the ArcGIS Python API, this operation is simplified by using the `FeatureLayer.edit_features()` method.\n",
    "\n",
    "This notebook will demonstrate:\n",
    "\n",
    "1. Accessing the Records feature layer\n",
    "2. Creating a branch version\n",
    "3. Creating a parcel record with attributes using `FeatureLayer.edit_features()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": true
   },
   "source": [
    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Part-3---Create-a-New-Parcel-Record\" data-toc-modified-id=\"Part-3---Create-a-New-Parcel-Record-1\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Part 3 - Create a New Parcel Record</a></span><ul class=\"toc-item\"><li><ul class=\"toc-item\"><li><span><a href=\"#Branch-versioning-setup\" data-toc-modified-id=\"Branch-versioning-setup-1.0.1\"><span class=\"toc-item-num\">1.0.1&nbsp;&nbsp;</span>Branch versioning setup</a></span></li><li><span><a href=\"#Create-a-new-feature-in-the-Records-feature-layer\" data-toc-modified-id=\"Create-a-new-feature-in-the-Records-feature-layer-1.0.2\"><span class=\"toc-item-num\">1.0.2&nbsp;&nbsp;</span>Create a new feature in the Records feature layer</a></span><ul class=\"toc-item\"><li><span><a href=\"#Prepare-the-attributes\" data-toc-modified-id=\"Prepare-the-attributes-1.0.2.1\"><span class=\"toc-item-num\">1.0.2.1&nbsp;&nbsp;</span>Prepare the attributes</a></span></li><li><span><a href=\"#Access-the-Records-FeatureLayer\" data-toc-modified-id=\"Access-the-Records-FeatureLayer-1.0.2.2\"><span class=\"toc-item-num\">1.0.2.2&nbsp;&nbsp;</span>Access the Records FeatureLayer</a></span></li><li><span><a href=\"#Insert-the-new-record-feature\" data-toc-modified-id=\"Insert-the-new-record-feature-1.0.2.3\"><span class=\"toc-item-num\">1.0.2.3&nbsp;&nbsp;</span>Insert the new record feature</a></span></li></ul></li><li><span><a href=\"#API-Ref-Documentation\" data-toc-modified-id=\"API-Ref-Documentation-1.0.3\"><span class=\"toc-item-num\">1.0.3&nbsp;&nbsp;</span>API Ref Documentation</a></span></li></ul></li></ul></li></ul></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcgis.gis import GIS\n",
    "from arcgis.features.layer import FeatureLayerCollection\n",
    "from arcgis.features.layer import FeatureLayer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Setting `verify_cert` to False is a security risk, use at your own risk.\n"
     ]
    }
   ],
   "source": [
    "base_server_url = (\n",
    "    \"https://rextapilnx02eb.mysite.com/server/rest/services/WashingtonCounty/\"\n",
    ")\n",
    "gis = GIS(\n",
    "    \"https://myenterprisesite.com/portal/\",\n",
    "    \"my_user_name\",\n",
    "    \"my_secure_password\",\n",
    "    verify_cert=False,\n",
    ")\n",
    "\n",
    "# Generate the enpoint urls for feature server and version management\n",
    "service_endpoints = [\"FeatureServer\", \"VersionManagementServer\"]\n",
    "service_urls = {url: base_server_url + url for url in service_endpoints}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Branch versioning setup\n",
    "- Get the Parcel Fabric `FeatureLayerCollection` (FLC)\n",
    "- Get the VersionManagementServer object from the FLC\n",
    "- Create a new branch version\n",
    "- Get the fully qualified (`owner.name`) version name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'my_user_name.new_record_version'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parcel_fabric_flc = FeatureLayerCollection(service_urls[\"FeatureServer\"], gis)\n",
    "version_management_server = parcel_fabric_flc.versions\n",
    "\n",
    "new_version_name = \"new_record_version\"\n",
    "version = version_management_server.create(new_version_name)\n",
    "fq_version_name = version[\"versionInfo\"][\"versionName\"]\n",
    "fq_version_name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a new feature in the Records feature layer\n",
    "- Get access to the correct feature layer\n",
    "- Create a dict containing some attributes for the new record\n",
    "- Get the FeatureLayer\n",
    "- Use `FeatureLayer.edit_features` to create the new feature and insert the attributes.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "    <b>Note:</b> It is expected that the new parcel record will contain an empty geometry.  When parcel features are attributed with this parcel record GUID, the Parcel Fabric Build function will generate a shape consisting of the outer boundaries of the associated parcel features.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'https://rextapilnx02eb.mysite.com/server/rest/services/WashingtonCounty/FeatureServer/1'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get the URL of the Records feature layer\n",
    "records_fl_url = [n for n in parcel_fabric_flc.layers if n.properties.name == \"Records\"]\n",
    "records_fl_url = records_fl_url[0].url\n",
    "records_fl_url"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Prepare the attributes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'attributes': {'name': 'ParcelRecord001'}, 'geometry': None}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# A name for the new record\n",
    "new_record_name = \"ParcelRecord001\"\n",
    "\n",
    "# Record information with empty geometry.  The geometry is created during Build\n",
    "record_dict = {\"attributes\": {\"name\": new_record_name}, \"geometry\": None}\n",
    "\n",
    "record_dict"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Access the Records FeatureLayer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<FeatureLayer url:\"https://rextapilnx02eb.mysite.com/server/rest/services/WashingtonCounty/FeatureServer/1\">"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "records_fl = FeatureLayer(records_fl_url, gis)\n",
    "records_fl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Insert the new record feature"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'addResults': [{'objectId': 112552,\n",
       "   'globalId': '{27518672-D139-45CA-B0DB-D07B96B7A6FD}',\n",
       "   'success': True}],\n",
       " 'updateResults': [],\n",
       " 'deleteResults': []}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create the new record within the new branch version\n",
    "new_record = records_fl.edit_features(adds=[record_dict], gdb_version=fq_version_name)\n",
    "\n",
    "new_record"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### API Ref Documentation\n",
    "\n",
    "- [ArcGIS Python API - Version Manager](/python/latest/api-reference/arcgis.features.managers.html#versionmanager)\n",
    "- [ArcGIS Python API - Parcel Fabric Manager](/python/latest/api-reference/arcgis.features.managers.html#parcelfabricmanager)\n",
    "- [ArcGIS REST API - VersionManagementServer](/rest/services-reference/enterprise/version-management-service.htm)\n",
    "- [ArcGIS REST API - ParcelFabricServer](/rest/services-reference/enterprise/overview-of-parcel-fabric-sevices.htm)\n",
    "- [ArcGIS Pro - Branch Versioning Scenarios](https://pro.arcgis.com/en/pro-app/latest/help/data/geodatabases/overview/branch-version-scenarios.htm)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.0"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": true,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "vscode": {
   "interpreter": {
    "hash": "ce21b655b4d6c9e397d5ad93d5666c623f49909f6d0cc2f72076dafcf1b3ecfb"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
